Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Defining a browse

This section describes some of the major functionality and style choices available when you define a browse, and the issues involved with those choices.

You can browse records by defining a browse for the query and opening the query. If you do not specifically enable the browse columns, the result is a read-only browse. Once the user finds and selects a record, your application can use the selected record, which the associated query puts in one or more associated buffers. This is the general syntax for a browse definition:

DEFINE BROWSE browse-name QUERY query-name    [ SHARE-LOCK | EXCLUSIVE-LOCK | NO-LOCK ]    DISPLAY { column-list | record [ EXCEPT field ... ] }    [ browse-enable-phrase ] browse-options-phrase .

As with all objects you define, you first give the browse a name. Next, you associate it with a query that you have previously defined. You can later associate the browse with a different query at run time by setting its QUERY attribute, but the query it’s defined for is the source of initial information about the buffers and fields you use to define columns in the browse.

Once again, NO-LOCK is the only reasonable locking option even for a browse on a database table and the only possible one for a browse on a temp-table, since temp-table don’t support record locking. It’s also the default, so you can leave out the NO-LOCK keyword altogether.

The DISPLAY phrase tells Progress which fields from the buffers in the query to display as columns in the browse. You can specify either an explicit space-delimited column-list or a list of one or more record buffers from the query. In the latter case, you can use the EXCEPT phrase to remove one or more fields from each record when it is displayed. The default is not to display any fields at all, so you must always include a DISPLAY phrase in your browse definition unless you want to define all the columns at run time, as you will learn to do in Chapter 20, " Creating and Using Dynamic Temp-tables and Browses."

If you just specify the DISPLAY list, the browse is read-only. None of its cells are enabled for input. The browse-enable-phrase lets you enable one or more cells for input:

ENABLE { column . . . | ALL [ EXCEPT column . . .] }

Each column in the ENABLE phrase must be a column in the DISPLAY list. If you want to enable all or almost all the columns, you can use the ALL keyword optionally followed by an EXCEPT list.

There are many options you can specify in the browse-options-phrase to customize the appearance and behavior of your browse. The phrase begins with the WITH keyword. Here are some of the more important options:

rows DOWN [ WIDTH width ] — You can specify how many rows to display in the viewport of the browse and, optionally, the width of the browse in characters. If the result of the query contains more rows than can be displayed at once, then the browse has a vertical scrollbar to let the user see them. If you use the DOWN phrase but don’t specify a WIDTH, Progress allocates enough horizontal space to display all the browse columns. Otherwise, you can use a horizontal scrollbar to let the user scroll left and right through the columns.
{ SIZE | SIZE-PIXELS } width BY height — As an alternative, you can define the size of the browse in both dimensions. This is the outer size of the browse including its border. When you use this option, Progress determines how many rows can be displayed at once, based on the height. This might result in a partial row being displayed at the bottom of the browse.
Note: You must specify either a DOWN phrase or a SIZE phrase in the browse options.
MULTIPLE | SINGLE — You can let the user select only a single row at a time or multiple rows. The default is SINGLE.
SEPARATORS | NO-SEPARATORS — Separators are vertical and horizontal lines between columns and rows. The default is NO-SEPARATORS, but you will probably find that your browses look better with SEPARATORS.
NO-ROW-MARKERS — By default, an updateable browse displays row markers, which let the user select currently displayed rows in an updateable browse widget without selecting any particular cell to update. This option prevents row markers from being displayed.
NO-LABELS — This option suppresses the display of column labels for the columns.
TITLE string — You can optionally display a title bar across the top of the browse.
NO-ASSIGN — If this option is not specified, data entered into an updateable browse is assigned on any action that results in a ROW-LEAVE event. The NO-ASSIGN option is intended for use with user-defined triggers on the ROW-LEAVE event. Essentially, when you specify this option, all data assignments by way of the updateable browse are up to you, the 4GL programmer. If you are defining a browse on a temp-table, then it is likely that the default support for automatic assigns back to the temp-table is appropriate because there are no transaction semantics to worry about. If you were to define an updateable browse directly against a database table, it is unlikely that the default assignment would be appropriate in any but the most trivial situations, so you would specify NO-ASSIGN to take control of the update process yourself.
NO-SCROLLBAR-VERTICAL | SCROLLBAR-VERTICAL — By default, a browse gets a vertical scrollbar, and this scrollbar is enabled whenever the size of the browse is not sufficient to display all the rows in the result set. You can suppress this default with the NO-SCROLLBAR-VERTICAL keyword. If you don’t have a vertical scrollbar, then the user must use the up and down arrow keys or other keys to navigate the browse. A browse always gets a horizontal scrollbar if the width of the browse is not sufficient to display all the columns.
ROW-HEIGHT-CHARS | ROW-HEIGHT-PIXELS — (GUI only) By default, Progress assigns a row height appropriate for the font size used in the browse. You can change this default by specifying the row height in either characters or pixels.
FIT-LAST-COLUMN — (GUI only) This option allows the browse to display so that there is no empty space to the right and no horizontal scroll bar, by widening or shrinking the last browse column’s width. When this attribute is specified, and the last browse column can be fully or partially displayed in the browse’s viewport, then the last browse column’s width is adjusted so that it fits within the viewport with no empty space to its right and no horizontal scroll bar. If the last browse column is fully contained in the viewport with empty space to its right, it grows so that its right edge is adjacent to the vertical scroll bar. If the last browse column extends outside the viewport, it shrinks so its right edge is adjacent to the vertical scroll bar and the horizontal scroll bar is not needed.